Inside Macintosh: QuickDraw GX Graphics /

Chapter 6 - Picture Shapes / Picture Shapes Reference

Functions / Getting and Setting Picture Geometries

GXSetPicture

You can use the GXSetPicture function to replace the information in the geometry of a picture shape.

void GXSetPicture(gxShape target, long count, 
                  const gxShape shapes[], const gxStyle styles[],
                  const gxInk inks[], 
                  const gxTransform transforms[]);

target

A reference to the picture shape whose geometry you want to replace.

count

The number of picture items in the new picture geometry.

shapes

An array of references to the shapes to include in the new picture geometry.

styles

An array of references to the styles you want to use as overriding styles in the new picture geometry. You may provide nil for this parameter if you do not want to change the existing overriding styles. You may provide the gxSetToNil constant to remove all of the existing overriding styles.

inks

An array of references to the inks you want to use as overriding inks in the new picture geometry. You may provide nil for this parameter if you do not want to change the existing overriding inks. You may provide the gxSetToNil constant to remove all of the existing overriding inks.

transforms

An array of references to the transforms you want to use as overriding transforms in the new picture geometry. You may provide nil for this parameter if you do not want to change the existing overriding transforms. You may provide the gxSetToNil constant to remove all of the existing overriding transforms.

DESCRIPTION

The GXSetPicture function replaces the geometry of the picture shape object referenced by the target parameter with a new geometry. To maintain correct owner counts, this function disposes of the shapes, styles, inks, and transforms referenced by the items of the original picture geometry.

In the count parameter, you specify the number of shapes in the new picture geometry, and in the shapes parameter you provide references to the shapes.

In the styles parameter, you specify references to the styles to use as overriding styles in the new picture geometry. Each item of this array overrides the style of the corresponding shape in the shapes array. For example, the first style you provide in the styles array becomes the overriding style for the first shape in the shapes array, and so on. Similarly, in the inks and transforms parameters you specify references to overriding inks and transforms.

You may specify 0 for the count parameter and nil for the shapes, styles, inks, and transforms parameters to create an empty picture--a picture containing no picture items. You may provide the gxSetToNil constant for the styles, inks, or transforms parameters even if you provide shape references in the shapes parameter. In this case, the newly created picture shape contains picture items, but those items contain no overriding styles, inks, or transforms, respectively.

You may also provide nil for an individual item of a styles, inks, or transforms array if you do not want the corresponding picture item to have an overriding style, ink, or transform.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
parameter_out_of_range	(debugging version)
cannot_set_item_shapes_to_nil	(debugging version)
cannot_use_original_item_shapes_when_growing_picture
	(debugging version)
Warnings
picture_expected	(debugging version)
shape_access_not_allowed	(debugging version)
picture_cannot_contain_itself	(debugging version)
cannot_dispose_locked_tag	(debugging version)
cannot_dispose_default_shape	(debugging version)
cannot_dispose_default_style	(debugging version)
cannot_dispose_default_ink	(debugging version)
cannot_dispose_default_transform	(debugging version)
cannot_dispose_default_colorProfile	(debugging version)

SEE ALSO

For information about picture items and their overriding styles, inks, and transforms, see "About Picture Shapes" beginning on page 6-3.

To examine the items of a picture geometry, use the GXGetPicture function, which is described on page 6-59.

To replace a subset of the items in a picture geometry, use the GXSetPictureParts function, which is described on page 6-65.

For information about disposing of shapes, see the chapter "Shape Objects" of Inside Macintosh: QuickDraw GX Objects.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help